Skip to main content

输出数据、定义样本数据和输出字段

本指南将解释什么是输出数据、样本数据和输出字段，以及如何在您的触发器或操作中修改它们。

输出数据​

每个 Zap 步骤必须向 Zapier 返回数据，以便在后续步骤中使用。默认情况下，输出数据是来自您的 API 的直接响应，但在某些情况下，您可能需要自定义响应数据，以使其更好地与 Zapier 兼容。以下是 Zap 步骤输出数据的通用原则：

尽可能分离数据，以使其在后续 Zap 步骤中更广泛可用。将名称拆分为单独的姓氏和名字，或给定名和姓氏对，并可选择包含一个完整名称字段。将地址拆分为其各个组成部分。

将日期-时间值格式化为 ISO 8601 标准，包括时区偏移，即使是 UTC 时间。避免使用 UNIX 或 Epoch 时间戳。如果您的 API 返回不同格式的日期，您可以在 API 调用自定义代码中修改日期响应。以下是可接受的日期-时间值示例：

  • 2023-12-15T01:15:13Z（或使用 -0000 代替 Z）
  • 2023-12-01T12:32:01-0800
  • 2023-12-01T12:32:01-08:00
  • 2023-12-13（仅日期值）

对于调度或日历应用程序集成，如果日期对用户很重要，可以额外包含一个易读的人性化日期。

将布尔值设置为 true 或 false。 不要使用 1 和 0 表示布尔值。

在列表和下拉菜单中包含值名称和 ID，以帮助用户选择正确的项目。

考虑在 API 调用的自定义代码中删除不必要的字段，以避免对用户造成混淆。

样本数据​

样本数据为 Zapier 提供用户未测试触发器或操作时的示例数据。尽管是可选的，但它对触发器尤为重要，对操作也很有用。

在 Zap 编辑器中，Zapier 会尝试检索或创建现有数据来测试触发器和操作。对于触发器，Zapier 会尝试获取最近添加或更新的项目。如果连接的帐户没有此项目的任何数据（轮询触发器）或未定义执行列表（REST Hook 触发器），用户将看到错误提示，表示没有可用项目。

用户也可以选择跳过这些测试步骤。在这两种情况下，Zapier 都会显示样本数据，以允许用户在后续 Zap 步骤中正确映射字段。

Field types Field types

样本数据必须是 JSON 格式的，并使用与您的应用程序 API 相同的字段名称。要么点击 Use Response from Test Data 按钮以导入上一次测试中您的应用程序发送给 Zapier 的字段，要么添加您自己的 JSON 格式字段。不得包含任何可识别个人身份的数据，且内容必须适合工作环境。

仅包括每次 Zap 运行时都存在的字段。 如果某个字段在样本数据中提供，用户可以将它映射到后续操作中的字段。

如果映射的字段在用户的 Zap 运行时不可用，该操作字段将为空，从而导致错误或意外结果。例如，假设您的样本数据如下所示：

{
  "id": 1,
  "first_name": "Jane",
  "last_name": "Suarez",
  "email_address": "janesz@example.com",
  "job_title": "Executive Director"
}

用户可能会将 job_title 信息映射到另一个应用程序（如 CRM）中的必填字段中。然后，当 Zap 运行时，如果 job_title 不可用，接收到的数据可能如下所示：

{
  "id": 5,
  "first_name": "Jacob",
  "last_name": "Giotto",
  "email_address": "jacob@example.com"
}

用户的 Zap 运行将出错，因为 CRM 的 API 在添加人员时要求 job_title 字段必须有数据，但这里没有。为避免这种情况，有几个 集成检查 要求样本数据和实际 Zap 运行数据必须匹配。

输出字段​

输出字段为您的 API 响应数据在后续 Zap 步骤中提供用户友好的标签。

默认情况下，Zapier 会对字段名称进行基本的人性化转换，包括大写单词并用空格替换下划线。您可以通过输出字段进一步自定义此设置。

如何修改您的样本数据和输出字段​

在您的触发器或操作设置中：

  1. 点击 Step 3 Define your Output 以展开此部分。
  2. 在 Sample Data 字段中，添加您的 JSON 格式的样本数据输出。
  3. 点击 Generate Output Field Definitions。
  4. 在 Output fields 中，您将看到一个表格，左侧是字段键，右侧是字段类型。在中间 Label 列中为每个字段添加人性化的名称，并在右侧列中选择字段类型。
  5. 点击 Save Output & Finish。

例如，如果您使用 GitHub 的 API 来监视新问题，API 会将问题名称称为 title。用户可能期望该字段被称为 Issue 或 Issue Title，因此您可以将输出字段定义为 Issue Title，而非默认的 "Title" 转换。

Field types